• A layer between the user and the various other OpenDoc subsystems
• Initializer of the document process and platform toolbox
• Creator of the ODSession object
• Provider of the base ODMenuBar object
• Handler of all document level content independent user actions
• Handler of all document level content independent AppleEvents
• The public class ODShellPlugIn
• The private class RealShell
• The function ShellMain
What is the Document Shell NOT?
• The Document Shell is NOT an application.
• The Document Shell has NO inherent content of its own.
Or, put another way, the Document Shell is content independent. (I thought that sounded better than content-free. )
Who calls the Document Shell?
• The Document Stub Application, a copy of which is launched for every document, calls ShellMain.
• The AppleEventManager calls the various AppleEvent handlers which the Shell registered whenever appropriate High Level Events come in.
Who does the Document Shell call?
• The platform specific process initialization api. (e.g. InitGraf)
• An ODSession object (creation & initialization)
• An ODMenuBar object (creation & initialization)
• The platform specific event gathering mechanism (WaitNextEvent)
• The Dispatcher to dispatch those events
• The StorageSystem to open, save a copy of, revert and close the Container, Document, and Draft for this process.
• The set of OpenDoc Shell Plug-Ins which are installed on the current system.
• The WindowState to open previously open windows of the draft
• The Root Part to open a new window if there were no previously open windows
• The DraftWindow class to list and manipulate the user drafts of the document
• The platform specific file system browser (StandardFile) in response to the Open… command
Which Document menu items does the Document Shell Handle?
• New - create a new document with the same kind as the root part of the frontmost window
• Open Document… - display the platform specific file system browser and launch the selected document with the appropriate application. If the user selects an OpenDoc document, then the Document Shell uses the same mechanism that the OpenDoc™ launcher application uses.
• Close - close the frontmost window. If that was the only document window then close the Container, Document, Draft and process. Shutdown the session. Holding down the option key changes this menu item to Close Document. Close Document is also what happens if the Shell receives a 'QUIT' event.
• Delete Document - Close the current document (saving if necessary) and place in the trash.
• Save - Save the current state of the document persistently.
• Save A Copy… - Save a copy of the document into another user specified container.
• Revert to Saved - Revert the document to the last persistently saved state.
• Drafts - Display a drafts window and allow the user to create, open and delete drafts.
Who handles the other Document menu items?
• Open, Insert… - the active part, i.e. the part with the selection focus
• Page Setup…, Print… - the root part of the frontmost window
How does the Document Shell open its document for editing?
The Document Shell gets the topmost draft in the document which represents the current persistent state of the document. It then creates a temporary draft where changes to the document are stored until the user saves. And finally it asks the WindowState object to internalize and display the windows which were previously open in the document. If there were no previously open windows, then the Document Shell asks the Root Part to Open and display itself in a new window.
How does the Document Shell Save?
The Document Shell asks the WindowState, and the temporary draft, to externalize. It then asks the temporary draft to save itself to the previous draft which represents the current persistent state of the document (SaveToPrevious).
How does the Document Shell Revert?
The Document Shell closes down everything which has been internalized from the temporary draft. The temporary draft is emptied out, and the WindowState is reinternalized from the temporary draft.
How does the Document Shell Close A Window?
The Document Shell tells the Window to close.
How does the Document Shell Close the Whole Document?
If the Document Shell closes the last document window, then it proceeds to also close down the entire document and process. First, the temporary draft is inspected to see if there were unsaved changes, and the user is given a chance to save them, discard them, or cancel the close. Once the temporary draft has been cleared out, it is removed. The document and container are released, which closes the document file. Finally the Dispatcher is instructed to Exit.
How does the Document Shell Save A Copy?
After the user specifies a new file using a platform specific file system browser (Standard PutFile on the Macintosh), the Document Shell creates a new Container, Document, and empty Draft. This empty Draft is told to copy the temporary draft into itself. The new Draft, Document & Container are released and the new file is closed.
What is the difference between User Drafts and Storage System Drafts?
• To the user, there is no current draft
• User drafts mean PAST versions
A closed document with one storage draft has no user drafts.
However, a document with one user draft, when closed has two storage drafts, and when open has three storage drafts.
• Documents start with one storage draft and no user drafts.
• Every time the user creates a user draft, the Document Shell creates a storage draft.
• When a document is closed or open readonly, the number of user drafts is the number of storage drafts minus one. That one extra storage draft represents the current state of the document. The user thinks of this as the document itself.
• When open for editing, the document has two more storage drafts than user drafts, and therefore the number of user drafts is the number of storage drafts minus two. The two extra storage drafts are the current persistent state of the document, and above that, the temporary draft where externalized storage units live until committed by a user Save action.
